home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / roomlist.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  10KB  |  320 lines
  1. /**
  2.  * @file roomlist.h Room List API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25.  
  26. #ifndef _GAIM_ROOMLIST_H_
  27. #define _GAIM_ROOMLIST_H_
  28.  
  29.  
  30. #include <glib/glist.h>
  31. #include "account.h"
  32.  
  33.  
  34. /**************************************************************************/
  35. /** Data Structures                                                       */
  36. /**************************************************************************/
  37.  
  38. typedef struct _GaimRoomlist GaimRoomlist;
  39. typedef struct _GaimRoomlistRoom GaimRoomlistRoom;
  40. typedef enum _GaimRoomlistRoomType GaimRoomlistRoomType;
  41. typedef struct _GaimRoomlistField GaimRoomlistField;
  42. typedef enum _GaimRoomlistFieldType GaimRoomlistFieldType;
  43. typedef struct _GaimRoomlistUiOps GaimRoomlistUiOps;
  44.  
  45. /**
  46.  * Represents a list of rooms for a given connection on a given protocol.
  47.  */
  48. struct _GaimRoomlist {
  49.     GaimAccount *account; /**< The account this list belongs to. */
  50.     GList *fields; /**< The fields. */
  51.     GList *rooms; /**< The list of rooms. */
  52.     gboolean in_progress; /**< The listing is in progress. */
  53.     gpointer ui_data; /**< UI private data. */
  54.     gpointer proto_data; /** Prpl private data. */
  55.     guint ref; /**< The reference count. */
  56. };
  57.  
  58. /**
  59.  * The types of rooms.
  60.  *
  61.  * These are ORable flags.
  62.  */
  63. enum _GaimRoomlistRoomType {
  64.     GAIM_ROOMLIST_ROOMTYPE_CATEGORY = 0x01, /**< It's a category, but not a room you can join. */
  65.     GAIM_ROOMLIST_ROOMTYPE_ROOM = 0x02,     /**< It's a room, like the kind you can join. */
  66. };
  67.  
  68. /**
  69.  * Represents a room.
  70.  */
  71. struct _GaimRoomlistRoom {
  72.     GaimRoomlistRoomType type; /**< The type of room. */
  73.     gchar *name; /**< The name of the room. */
  74.     GList *fields; /**< Other fields. */
  75.     GaimRoomlistRoom *parent; /**< The parent room, or NULL. */
  76.     gboolean expanded_once; /**< A flag the UI uses to avoid multiple expand prpl cbs. */
  77. };
  78.  
  79. /**
  80.  * The types of fields.
  81.  */
  82. enum _GaimRoomlistFieldType {
  83.     GAIM_ROOMLIST_FIELD_BOOL,
  84.     GAIM_ROOMLIST_FIELD_INT,
  85.     GAIM_ROOMLIST_FIELD_STRING, /**< We do a g_strdup on the passed value if it's this type. */
  86. };
  87.  
  88. /**
  89.  * A field a room might have.
  90.  */
  91. struct _GaimRoomlistField {
  92.     GaimRoomlistFieldType type; /**< The type of field. */
  93.     gchar *label; /**< The i18n user displayed name of the field. */
  94.     gchar *name; /**< The internal name of the field. */
  95.     gboolean hidden; /**< Hidden? */
  96. };
  97.  
  98. /**
  99.  * The room list ops to be filled out by the UI.
  100.  */
  101. struct _GaimRoomlistUiOps {
  102.     void (*show_with_account)(GaimAccount *account); /**< Force the ui to pop up a dialog and get the list */
  103.     void (*new)(GaimRoomlist *list); /**< A new list was created. */
  104.     void (*set_fields)(GaimRoomlist *list, GList *fields); /**< Sets the columns. */
  105.     void (*add_room)(GaimRoomlist *list, GaimRoomlistRoom *room); /**< Add a room to the list. */
  106.     void (*in_progress)(GaimRoomlist *list, gboolean flag); /**< Are we fetching stuff still? */
  107.     void (*destroy)(GaimRoomlist *list); /**< We're destroying list. */
  108. };
  109.  
  110.  
  111. #ifdef __cplusplus
  112. extern "C" {
  113. #endif
  114.  
  115. /**************************************************************************/
  116. /** @name Room List API                                                   */
  117. /**************************************************************************/
  118. /*@{*/
  119.  
  120. /**
  121.  * This is used to get the room list on an account, asking the UI
  122.  * to pop up a dialog with the specified account already selected,
  123.  * and pretend the user clicked the get list button.
  124.  * While we're pretending, predend I didn't say anything about dialogs
  125.  * or buttons, since this is the core.
  126.  *
  127.  * @param account The account to get the list on.
  128.  */
  129. void gaim_roomlist_show_with_account(GaimAccount *account);
  130.  
  131. /**
  132.  * Returns a newly created room list object.
  133.  *
  134.  * It has an initial reference count of 1.
  135.  *
  136.  * @param account The account that's listing rooms.
  137.  * @return The new room list handle.
  138.  */
  139. GaimRoomlist *gaim_roomlist_new(GaimAccount *account);
  140.  
  141. /**
  142.  * Increases the reference count on the room list.
  143.  *
  144.  * @param list The object to ref.
  145.  */
  146. void gaim_roomlist_ref(GaimRoomlist *list);
  147.  
  148. /**
  149.  * Decreases the reference count on the room list.
  150.  *
  151.  * The room list will be destroyed when this reaches 0.
  152.  *
  153.  * @param list The room list object to unref and possibly
  154.  *             destroy.
  155.  */
  156. void gaim_roomlist_unref(GaimRoomlist *list);
  157.  
  158. /**
  159.  * Set the different field types and their names for this protocol.
  160.  *
  161.  * This must be called before gaim_roomlist_room_add().
  162.  *
  163.  * @param list The room list.
  164.  * @param fields A GList of GaimRoomlistField's. UI's are encouraged
  165.  *               to default to displaying them in the order given.
  166.  */
  167. void gaim_roomlist_set_fields(GaimRoomlist *list, GList *fields);
  168.  
  169. /**
  170.  * Set the "in progress" state of the room list.
  171.  *
  172.  * The UI is encouraged to somehow hint to the user
  173.  * whether or not we're busy downloading a room list or not.
  174.  *
  175.  * @param list The room list.
  176.  * @param in_progress We're downloading it, or we're not.
  177.  */
  178. void gaim_roomlist_set_in_progress(GaimRoomlist *list, gboolean in_progress);
  179.  
  180. /**
  181.  * Gets the "in progress" state of the room list.
  182.  *
  183.  * The UI is encouraged to somehow hint to the user
  184.  * whether or not we're busy downloading a room list or not.
  185.  *
  186.  * @param list The room list.
  187.  * @return True if we're downloading it, or false if we're not.
  188.  */
  189. gboolean gaim_roomlist_get_in_progress(GaimRoomlist *list);
  190.  
  191. /**
  192.  * Adds a room to the list of them.
  193.  *
  194.  * @param list The room list.
  195.  * @param room The room to add to the list. The GList of fields must be in the same
  196.                order as was given in gaim_roomlist_set_fields().
  197. */
  198. void gaim_roomlist_room_add(GaimRoomlist *list, GaimRoomlistRoom *room);
  199.  
  200. /**
  201.  * Returns a GaimRoomlist structure from the prpl, and
  202.  * instructs the prpl to start fetching the list.
  203.  *
  204.  * @param gc The GaimConnection to have get a list.
  205.  *
  206.  * @return A GaimRoomlist* or @c NULL if the protocol
  207.  *         doesn't support that.
  208.  */
  209. GaimRoomlist *gaim_roomlist_get_list(GaimConnection *gc);
  210.  
  211. /**
  212.  * Tells the prpl to stop fetching the list.
  213.  * If this is possible and done, the prpl will
  214.  * call set_in_progress with @c FALSE and possibly
  215.  * unref the list if it took a reference.
  216.  *
  217.  * @param list The room list to cancel a get_list on.
  218.  */
  219. void gaim_roomlist_cancel_get_list(GaimRoomlist *list);
  220.  
  221. /**
  222.  * Tells the prpl that a category was expanded.
  223.  *
  224.  * On some protocols, the rooms in the category
  225.  * won't be fetched until this is called.
  226.  *
  227.  * @param list     The room list.
  228.  * @param category The category that was expanded. The expression
  229.  *                 (category->type & GAIM_ROOMLIST_ROOMTYPE_CATEGORY)
  230.  *                 must be true.
  231.  */
  232. void gaim_roomlist_expand_category(GaimRoomlist *list, GaimRoomlistRoom *category);
  233.  
  234. /*@}*/
  235.  
  236. /**************************************************************************/
  237. /** @name Room API                                                        */
  238. /**************************************************************************/
  239. /*@{*/
  240.  
  241. /**
  242.  * Creates a new room, to be added to the list.
  243.  *
  244.  * @param type The type of room.
  245.  * @param name The name of the room.
  246.  * @param parent The room's parent, if any.
  247.  *
  248.  * @return A new room.
  249.  */
  250. GaimRoomlistRoom *gaim_roomlist_room_new(GaimRoomlistRoomType type, const gchar *name,
  251.                                          GaimRoomlistRoom *parent);
  252.  
  253. /**
  254.  * Adds a field to a room.
  255.  *
  256.  * @param list The room list the room belongs to.
  257.  * @param room The room.
  258.  * @param field The field to append. Strings get g_strdup'd internally.
  259.  */
  260. void gaim_roomlist_room_add_field(GaimRoomlist *list, GaimRoomlistRoom *room, gconstpointer field);
  261.  
  262. /**
  263.  * Join a room, given a GaimRoomlistRoom and it's associated GaimRoomlist.
  264.  *
  265.  * @param list The room list the room belongs to.
  266.  * @param room The room to join.
  267.  */
  268. void gaim_roomlist_room_join(GaimRoomlist *list, GaimRoomlistRoom *room);
  269.  
  270. /*@}*/
  271.  
  272. /**************************************************************************/
  273. /** @name Room Field API                                                  */
  274. /**************************************************************************/
  275. /*@{*/
  276.  
  277. /**
  278.  * Creates a new field.
  279.  *
  280.  * @param type   The type of the field.
  281.  * @param label  The i18n'ed, user displayable name.
  282.  * @param name   The internal name of the field.
  283.  * @param hidden Hide the field.
  284.  *
  285.  * @return A new GaimRoomlistField, ready to be added to a GList and passed to
  286.  *         gaim_roomlist_set_fields().
  287.  */
  288. GaimRoomlistField *gaim_roomlist_field_new(GaimRoomlistFieldType type,
  289.                                            const gchar *label, const gchar *name,
  290.                                            gboolean hidden);
  291. /*@}*/
  292.  
  293. /**************************************************************************/
  294. /** @name UI Registration Functions                                       */
  295. /**************************************************************************/
  296. /*@{*/
  297.  
  298. /**
  299.  * Sets the UI operations structure to be used in all gaim room lists.
  300.  *
  301.  * @param ops The UI operations structure.
  302.  */
  303. void gaim_roomlist_set_ui_ops(GaimRoomlistUiOps *ops);
  304.  
  305. /**
  306.  * Returns the gaim window UI operations structure to be used in
  307.  * new windows.
  308.  *
  309.  * @return A filled-out GaimRoomlistUiOps structure.
  310.  */
  311. GaimRoomlistUiOps *gaim_roomlist_get_ui_ops(void);
  312.  
  313. /*@}*/
  314.  
  315. #ifdef __cplusplus
  316. }
  317. #endif
  318.  
  319. #endif /* _GAIM_ROOMLIST_H_ */
  320.